/**
 * <h3>ISuggestionService</h3>
 * <p> 建议信息管理服务接口 </p>
 *
 * <h3>功能描述</h3>
 * <p> 定义建议信息增删改查等基础业务操作，包括用户建议提交、建议管理、个人建议查询等 </p>
 * <p> 支持建议的创建、修改、删除、查询等核心业务逻辑，提供用户反馈管理功能 </p>
 *
 * <h3>元数据</h3>
 * <ul>
 *    <li> 作者：郭强 </li>
 *    <li> 创建日期：2025年05月22日 21:15:20 </li>
 * </ul>
 *
 * <h3>其他信息</h3>
 * <ul>
 *    <li> 参考链接：<a href="https://example.com">官方网页</a></li>
 *    <li> 示例代码：{@code selectSuggestionList(SuggestionDTO dto)} </li>
 * </ul>
 *
 * @apiNote 接口方法需保证事务一致性与线程安全；支持用户个人建议查询
 * @implSpec 继承自 {@link IService<SuggestionDTO>}，扩展了按条件查询、按ID获取等方法
 * @since 1.0.0
 */

package com.dnndo.system.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.dnndo.system.domain.Suggestion;
import com.dnndo.system.domain.dto.SuggestionDTO;

import java.util.List;

/**
 * 建议服务接口
 * 
 * @see com.dnndo.system.domain.Suggestion
 * @see com.dnndo.system.domain.dto.SuggestionDTO
 * @see com.dnndo.system.service.impl.SuggestionServiceImpl
 */
public interface ISuggestionService extends IService<SuggestionDTO> {

    /**
     * 根据条件分页查询建议列表
     *
     * @param dto 建议查询条件封装对象，包含建议名称、类型、省份等过滤条件
     * @return List<Suggestion> 符合条件的建议信息列表
     * @see com.dnndo.system.domain.dto.SuggestionDTO
     * @see com.dnndo.system.domain.Suggestion
     */
    List<Suggestion> selectSuggestionList(SuggestionDTO dto);

    /**
     * 根据建议ID获取详细信息
     *
     * @param suggestionId 建议唯一标识符
     * @param id 用户ID，用于权限验证
     * @return SuggestionDTO 包含建议详细信息的数据对象
     * @see com.dnndo.system.domain.dto.SuggestionDTO
     */
    SuggestionDTO selectSuggestionListById(Long suggestionId, Long id);

    /**
     * 修改已有建议信息
     *
     * @param suggestionDTO 包含更新字段的建议数据对象
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.SuggestionDTO
     */
    int updateSuggestionById(SuggestionDTO suggestionDTO);

    /**
     * 新增建议信息
     *
     * @param suggestionDTO 包含新增字段的建议数据对象
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.SuggestionDTO
     */
    int insertSuggestion(SuggestionDTO suggestionDTO);

    /**
     * 删除指定ID的建议信息
     *
     * @param suggestionId 要删除的建议唯一标识符
     * @return int 受影响的数据库记录数，用于判断操作是否成功
     * @see com.dnndo.system.domain.dto.SuggestionDTO
     */
    int deleteSuggestionById(Integer suggestionId);

    /**
     * 获取用户自己的投诉建议
     *
     * @param userId 用户ID
     * @return List<SuggestionDTO> 用户提交的建议列表
     * @see com.dnndo.system.domain.dto.SuggestionDTO
     */
    List<SuggestionDTO> selectMySuggestionList(long userId);

}
